|
API 定义完整示例api 示例 下文仅展示 api 文件的完整写法和对应语法块的功能说明，如需查看 api 规范定义，可参考 《API 规范》 syntax = "v1"info ( title: "api 文件完整示例写法" desc: "演示如何编写 api 文件" author: "keson.an" date: "2022 年 12 月 26 日" version: "v1")type UpdateReq { Arg1 string `json:"arg1"`}type ListItem { Value1 string `json:"value1"`}type LoginReq { Username string `json:"username"` Password string `json:"password"`}type LoginResp { Name string `json:"name"`}type FormExampleReq { Name string `form:"name"`}type PathExampleReq { // path 标签修饰的 id 必须与请求路由中的片段对应，如 // id 在 service 语法块的请求路径上一定会有 :id 对应，见下文。 ID string `path:"id"`}type PathExampleResp { Name string `json:"name"`}@server ( jwt: Auth // 对当前 Foo 语法块下的所有路由，开启 jwt 认证，不需要则请删除此行 prefix: /v1 // 对当前 Foo 语法块下的所有路由，新增 /v1 路由前缀，不需要则请删除此行 group: g1 // 对当前 Foo 语法块下的所有路由，路由归并到 g1 目录下，不需要则请删除此行 timeout: 3s // 对当前 Foo 语法块下的所有路由进行超时配置，不需要则请删除此行 middleware: AuthInterceptor // 对当前 Foo 语法块下的所有路由添加中间件，不需要则请删除此行 maxBytes: 1048576 // 对当前 Foo 语法块下的所有路由添加请求体大小控制，单位为 byte,goctl 版本 >= 1.5.0 才支持)service Foo { // 定义没有请求体和响应体的接口，如 ping @handler ping get /ping // 定义只有请求体的接口，如更新信息 @handler update post /update (UpdateReq) // 定义只有响应体的结构，如获取全部信息列表 @handler list get /list returns ([]ListItem) // 定义有结构体和响应体的接口，如登录 @handler login post /login (LoginReq) returns (LoginResp) // 定义表单请求 @handler formExample post /form/example (FormExampleReq) // 定义 path 参数 @handler pathExample get /path/example/:id (PathExampleReq) returns (PathExampleResp)}
|